<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Models of CallPolicies</title>
<link rel="stylesheet" href="../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="Boost.Python Reference Manual">
<link rel="up" href="../function_invocation_and_creation.html" title="Chapter 4. Function Invocation and Creation">
<link rel="prev" href="function_documentation.html" title="Function documentation">
<link rel="next" href="models_of_resultconverter.html" title="Models of ResultConverter">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="" width="" height="" src="../../images/boost.png"></td></tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="function_documentation.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="models_of_resultconverter.html"><img src="../../images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="function_invocation_and_creation.models_of_callpolicies"></a><a class="link" href="models_of_callpolicies.html" title="Models of CallPolicies">Models
      of CallPolicies</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici">boost/python/default_call_policies.hpp</a></span></dt>
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp">boost/python/return_arg.hpp</a></span></dt>
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref">boost/python/return_internal_reference.hpp</a></span></dt>
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_value_policy">boost/python/return_value_policy.hpp</a></span></dt>
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_">boost/python/with_custodian_and_ward.hpp</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici" title="boost/python/default_call_policies.hpp">boost/python/default_call_policies.hpp</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.class_default_call_policies">Class
          <code class="computeroutput"><span class="identifier">default_call_policies</span></code></a></span></dt>
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.class_default_call_policies_stat">Class
          <code class="computeroutput"><span class="identifier">default_call_policies</span></code> static
          functions</a></span></dt>
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.class_default_result_converter">Class
          <code class="computeroutput"><span class="identifier">default_result_converter</span></code></a></span></dt>
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.class_default_result_converter_m">Class
          <code class="computeroutput"><span class="identifier">default_result_converter</span></code>
          metafunctions</a></span></dt>
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.class_default_call_policies"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.class_default_call_policies" title="Class default_call_policies">Class
          <code class="computeroutput"><span class="identifier">default_call_policies</span></code></a>
</h4></div></div></div>
<p>
            <code class="computeroutput"><span class="identifier">default_call_policies</span></code>
            is a model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a>
            with no <code class="computeroutput"><span class="identifier">precall</span></code> or <code class="computeroutput"><span class="identifier">postcall</span></code> behavior and a <code class="computeroutput"><span class="identifier">result_converter</span></code> which handles by-value
            returns. Wrapped C++ functions and member functions <code class="computeroutput"><span class="identifier">use</span>
            <span class="identifier">default_call_policies</span></code> unless
            otherwise specified. You may find it convenient to derive new models
            of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a>
            from <code class="computeroutput"><span class="identifier">default_call_policies</span></code>.
          </p>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span>
<span class="special">{</span>
    <span class="keyword">struct</span> <span class="identifier">default_call_policies</span>
    <span class="special">{</span>
        <span class="keyword">static</span> <span class="keyword">bool</span> <span class="identifier">precall</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*);</span>
        <span class="keyword">static</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">postcall</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">result</span><span class="special">);</span>
        <span class="keyword">typedef</span> <span class="identifier">default_result_converter</span> <span class="identifier">result_converter</span><span class="special">;</span>
        <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Sig</span><span class="special">&gt;</span> <span class="keyword">struct</span> <span class="identifier">extract_return_type</span> <span class="special">:</span> <span class="identifier">mpl</span><span class="special">::</span><span class="identifier">front</span><span class="special">&lt;</span><span class="identifier">Sig</span><span class="special">&gt;{};</span>
    <span class="special">};</span>
<span class="special">}}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.class_default_call_policies_stat"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.class_default_call_policies_stat" title="Class default_call_policies static functions">Class
          <code class="computeroutput"><span class="identifier">default_call_policies</span></code> static
          functions</a>
</h4></div></div></div>
<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">precall</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*);</span></pre>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Returns</span></dt>
<dd><p>
                  true
                </p></dd>
<dt><span class="term">Throws</span></dt>
<dd><p>
                  nothing
                </p></dd>
</dl>
</div>
<pre class="programlisting"><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">postcall</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">result</span><span class="special">);</span></pre>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Returns</span></dt>
<dd><p>
                  result
                </p></dd>
<dt><span class="term">Throws</span></dt>
<dd><p>
                  nothing
                </p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.class_default_result_converter"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.class_default_result_converter" title="Class default_result_converter">Class
          <code class="computeroutput"><span class="identifier">default_result_converter</span></code></a>
</h4></div></div></div>
<p>
            default_result_converter is a model of <a class="link" href="../concepts/resultconverter.html#concepts.resultconverter.resultconvertergenerator_concept" title="ResultConverterGenerator Concept Requirements"><code class="computeroutput"><span class="identifier">ResultConverterGenerator</span></code></a> which
            can be used to wrap C++ functions returning non-pointer types, <code class="computeroutput"><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*</span></code>, and <code class="computeroutput"><span class="identifier">PyObject</span><span class="special">*</span></code>, by-value.
          </p>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span>
<span class="special">{</span>
    <span class="keyword">struct</span> <span class="identifier">default_result_converter</span>
    <span class="special">{</span>
        <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span> <span class="keyword">struct</span> <span class="identifier">apply</span><span class="special">;</span>
    <span class="special">};</span>
<span class="special">}}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.class_default_result_converter_m"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.class_default_result_converter_m" title="Class default_result_converter metafunctions">Class
          <code class="computeroutput"><span class="identifier">default_result_converter</span></code>
          metafunctions</a>
</h4></div></div></div>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span> <span class="keyword">struct</span> <span class="identifier">apply</span></pre>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Requires</span></dt>
<dd><p>
                  T is not a reference type. If T is a pointer type, T is const char*
                  or PyObject*.
                </p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
                  typedef to_python_value&lt;T const&amp;&gt; type;
                </p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.example"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_default_call_polici.example" title="Example">Example</a>
</h4></div></div></div>
<p>
            This example comes from the Boost.Python implementation itself. Because
            the return_value_policy class template does not implement precall or
            postcall behavior, its default base class is default_call_policies:
          </p>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Handler</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Base</span> <span class="special">=</span> <span class="identifier">default_call_policies</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">return_value_policy</span> <span class="special">:</span> <span class="identifier">Base</span>
<span class="special">{</span>
   <span class="keyword">typedef</span> <span class="identifier">Handler</span> <span class="identifier">result_converter</span><span class="special">;</span>
<span class="special">};</span>
</pre>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp" title="boost/python/return_arg.hpp">boost/python/return_arg.hpp</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.class_return_arg">Class
          <code class="computeroutput"><span class="identifier">return_arg</span></code></a></span></dt>
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.class_return_arg_static_function">Class
          <code class="computeroutput"><span class="identifier">return_arg</span></code> static functions</a></span></dt>
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.class_template_return_self">Class
          template <code class="computeroutput"><span class="identifier">return_self</span></code></a></span></dt>
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.introduction"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.introduction" title="Introduction">Introduction</a>
</h4></div></div></div>
<p>
            <code class="computeroutput"><span class="identifier">return_arg</span></code> and <code class="computeroutput"><span class="identifier">return_self</span></code> instantiations are models
            of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a>
            which return the specified argument parameter (usually <code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>)
            of a wrapped (member) function.
          </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.class_return_arg"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.class_return_arg" title="Class return_arg">Class
          <code class="computeroutput"><span class="identifier">return_arg</span></code></a>
</h4></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                    <p>
                      Parameter
                    </p>
                  </th>
<th>
                    <p>
                      Requirements
                    </p>
                  </th>
<th>
                    <p>
                      Description
                    </p>
                  </th>
<th>
                    <p>
                      Default
                    </p>
                  </th>
</tr></thead>
<tbody>
<tr>
<td>
                    <p>
                      arg_pos
                    </p>
                  </td>
<td>
                    <p>
                      A positive compile-time constant of type <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></code>.
                    </p>
                  </td>
<td>
                    <p>
                      the position of the argument to be returned.
                    </p>
                  </td>
<td>
                    <p>
                      1
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      Base
                    </p>
                  </td>
<td>
                    <p>
                      A model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a>
                    </p>
                  </td>
<td>
                    <p>
                      Used for policy composition. Any <code class="computeroutput"><span class="identifier">result_converter</span></code>
                      it supplies will be overridden by <code class="computeroutput"><span class="identifier">return_arg</span></code>,
                      but its <code class="computeroutput"><span class="identifier">precall</span></code>
                      and <code class="computeroutput"><span class="identifier">postcall</span></code>
                      policies are composed as described here <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a>.
                    </p>
                  </td>
<td>
                    <p>
                      default_call_policies
                    </p>
                  </td>
</tr>
</tbody>
</table></div>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span>
<span class="special">{</span>
   <span class="keyword">template</span> <span class="special">&lt;</span><span class="identifier">size_t</span> <span class="identifier">arg_pos</span><span class="special">=</span><span class="number">1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Base</span> <span class="special">=</span> <span class="identifier">default_call_policies</span><span class="special">&gt;</span>
   <span class="keyword">struct</span> <span class="identifier">return_arg</span> <span class="special">:</span> <span class="identifier">Base</span>
   <span class="special">{</span>
      <span class="keyword">static</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">postcall</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">result</span><span class="special">);</span>
      <span class="keyword">struct</span> <span class="identifier">result_converter</span><span class="special">{</span> <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span> <span class="keyword">struct</span> <span class="identifier">apply</span><span class="special">;</span> <span class="special">};</span>
      <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Sig</span><span class="special">&gt;</span> <span class="keyword">struct</span> <span class="identifier">extract_return_type</span> <span class="special">:</span> <span class="identifier">mpl</span><span class="special">::</span><span class="identifier">at_c</span><span class="special">&lt;</span><span class="identifier">Sig</span><span class="special">,</span> <span class="identifier">arg_pos</span><span class="special">&gt;{};</span>

   <span class="special">};</span>
<span class="special">}}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.class_return_arg_static_function"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.class_return_arg_static_function" title="Class return_arg static functions">Class
          <code class="computeroutput"><span class="identifier">return_arg</span></code> static functions</a>
</h4></div></div></div>
<pre class="programlisting"><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">postcall</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">args</span><span class="special">,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">result</span><span class="special">);</span></pre>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Requires</span></dt>
<dd><p>
                  <code class="computeroutput"><span class="identifier">PyTuple_Check</span><span class="special">(</span><span class="identifier">args</span><span class="special">)</span>
                  <span class="special">!=</span> <span class="number">0</span></code>
                  and <code class="computeroutput"><span class="identifier">PyTuple_Size</span><span class="special">(</span><span class="identifier">args</span><span class="special">)</span> <span class="special">!=</span> <span class="number">0</span></code>
                </p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
                  PyTuple_GetItem(args,arg_pos-1)
                </p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.class_template_return_self"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.class_template_return_self" title="Class template return_self">Class
          template <code class="computeroutput"><span class="identifier">return_self</span></code></a>
</h4></div></div></div>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span>
<span class="special">{</span>
   <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Base</span> <span class="special">=</span> <span class="identifier">default_call_policies</span><span class="special">&gt;</span>
   <span class="keyword">struct</span> <span class="identifier">return_self</span>
     <span class="special">:</span> <span class="identifier">return_arg</span><span class="special">&lt;</span><span class="number">1</span><span class="special">,</span><span class="identifier">Base</span><span class="special">&gt;</span>
   <span class="special">{};</span>
<span class="special">}}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.example"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_arg_hpp.example" title="Example">Example</a>
</h4></div></div></div>
<p>
            C++ module definition:
          </p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">return_arg</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>

<span class="keyword">struct</span> <span class="identifier">Widget</span>
<span class="special">{</span>
   <span class="identifier">Widget</span><span class="special">()</span> <span class="special">:</span><span class="identifier">sensitive_</span><span class="special">(</span><span class="keyword">true</span><span class="special">){}</span>
   <span class="keyword">bool</span> <span class="identifier">get_sensitive</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">sensitive_</span><span class="special">;</span> <span class="special">}</span>
   <span class="keyword">void</span> <span class="identifier">set_sensitive</span><span class="special">(</span><span class="keyword">bool</span> <span class="identifier">s</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">this</span><span class="special">-&gt;</span><span class="identifier">sensitive_</span> <span class="special">=</span> <span class="identifier">s</span><span class="special">;</span> <span class="special">}</span>
 <span class="keyword">private</span><span class="special">:</span>
   <span class="keyword">bool</span> <span class="identifier">sensitive_</span><span class="special">;</span>
<span class="special">};</span>

<span class="keyword">struct</span> <span class="identifier">Label</span> <span class="special">:</span> <span class="identifier">Widget</span>
<span class="special">{</span>
   <span class="identifier">Label</span><span class="special">()</span> <span class="special">{}</span>

   <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span>  <span class="identifier">get_label</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">label_</span><span class="special">;</span> <span class="special">}</span>
   <span class="keyword">void</span> <span class="identifier">set_label</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&amp;</span><span class="identifier">l</span><span class="special">){</span> <span class="identifier">label_</span> <span class="special">=</span> <span class="identifier">l</span><span class="special">;</span> <span class="special">}</span>

 <span class="keyword">private</span><span class="special">:</span>
   <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">label_</span><span class="special">;</span>
<span class="special">};</span>

<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span>
<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">return_self_ext</span><span class="special">)</span>
<span class="special">{</span>
   <span class="identifier">class_</span><span class="special">&lt;</span><span class="identifier">widget</span><span class="special">&gt;(</span><span class="string">"Widget"</span><span class="special">)</span>
      <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"sensitive"</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">Widget</span><span class="special">::</span><span class="identifier">get_sensitive</span><span class="special">)</span>
      <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"sensitive"</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">Widget</span><span class="special">::</span><span class="identifier">set_sensitive</span><span class="special">,</span> <span class="identifier">return_self</span><span class="special">&lt;&gt;())</span>
      <span class="special">;</span>

   <span class="identifier">class_</span><span class="special">&lt;</span><span class="identifier">Label</span><span class="special">,</span> <span class="identifier">bases</span><span class="special">&lt;</span><span class="identifier">Widget</span><span class="special">&gt;</span> <span class="special">&gt;(</span><span class="string">"Label"</span><span class="special">)</span>
      <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"label"</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">Label</span><span class="special">::</span><span class="identifier">get_label</span><span class="special">)</span>
      <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"label"</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">Label</span><span class="special">::</span><span class="identifier">set_label</span><span class="special">,</span> <span class="identifier">return_self</span><span class="special">&lt;&gt;())</span>
      <span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
            Python code:
          </p>
<pre class="programlisting"><span class="special">&gt;&gt;&gt;</span> <span class="identifier">from</span> <span class="identifier">return_self_ext</span> <span class="identifier">import</span> <span class="special">*</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">l1</span> <span class="special">=</span> <span class="identifier">Label</span><span class="special">().</span><span class="identifier">label</span><span class="special">(</span><span class="string">"foo"</span><span class="special">).</span><span class="identifier">sensitive</span><span class="special">(</span><span class="keyword">false</span><span class="special">)</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">l2</span> <span class="special">=</span> <span class="identifier">Label</span><span class="special">().</span><span class="identifier">sensitive</span><span class="special">(</span><span class="keyword">false</span><span class="special">).</span><span class="identifier">label</span><span class="special">(</span><span class="string">"foo"</span><span class="special">)</span>
</pre>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref" title="boost/python/return_internal_reference.hpp">boost/python/return_internal_reference.hpp</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.class_template_return_internal_r">Class
          template <code class="computeroutput"><span class="identifier">return_internal_reference</span></code></a></span></dt>
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.class_return_internal_reference_">Class
          <code class="computeroutput"><span class="identifier">return_internal_reference</span></code>
          static functions</a></span></dt>
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.introduction"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.introduction" title="Introduction">Introduction</a>
</h4></div></div></div>
<p>
            <code class="computeroutput"><span class="identifier">return_internal_reference</span></code>
            instantiations are models of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a> which allow pointers
            and references to objects held internally by a free or member function
            argument or from the target of a member function to be returned safely
            without making a copy of the referent. The default for its first template
            argument handles the common case where the containing object is the target
            (<code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>)
            of a wrapped member function.
          </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.class_template_return_internal_r"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.class_template_return_internal_r" title="Class template return_internal_reference">Class
          template <code class="computeroutput"><span class="identifier">return_internal_reference</span></code></a>
</h4></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                    <p>
                      Parameter
                    </p>
                  </th>
<th>
                    <p>
                      Requirements
                    </p>
                  </th>
<th>
                    <p>
                      Description
                    </p>
                  </th>
<th>
                    <p>
                      Default
                    </p>
                  </th>
</tr></thead>
<tbody>
<tr>
<td>
                    <p>
                      owner_arg
                    </p>
                  </td>
<td>
                    <p>
                      A positive compile-time constant of type <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></code>.
                    </p>
                  </td>
<td>
                    <p>
                      The index of the parameter which contains the object to which
                      the reference or pointer is being returned. If used to wrap
                      a member function, parameter 1 is the target object (<code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>).
                      Note that if the target Python object type doesn't support
                      weak references, a Python TypeError exception will be raised
                      when the function being wrapped is called.
                    </p>
                  </td>
<td>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      Base
                    </p>
                  </td>
<td>
                    <p>
                      A model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a>
                    </p>
                  </td>
<td>
                    <p>
                      Used for policy composition. Any <code class="computeroutput"><span class="identifier">result_converter</span></code>
                      it supplies will be overridden by <code class="computeroutput"><span class="identifier">return_internal_reference</span></code>,
                      but its <code class="computeroutput"><span class="identifier">precall</span></code>
                      and <code class="computeroutput"><span class="identifier">postcall</span></code>
                      policies are composed as described here <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a>.
                    </p>
                  </td>
<td>
                    <p>
                      default_call_policies
                    </p>
                  </td>
</tr>
</tbody>
</table></div>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span>
<span class="special">{</span>
   <span class="keyword">template</span> <span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">owner_arg</span> <span class="special">=</span> <span class="number">1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Base</span> <span class="special">=</span> <span class="identifier">default_call_policies</span><span class="special">&gt;</span>
   <span class="keyword">struct</span> <span class="identifier">return_internal_reference</span> <span class="special">:</span> <span class="identifier">Base</span>
   <span class="special">{</span>
      <span class="keyword">static</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">postcall</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">result</span><span class="special">);</span>
      <span class="keyword">typedef</span> <span class="identifier">reference_existing_object</span> <span class="identifier">result_converter</span><span class="special">;</span>
   <span class="special">};</span>
<span class="special">}}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.class_return_internal_reference_"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.class_return_internal_reference_" title="Class return_internal_reference static functions">Class
          <code class="computeroutput"><span class="identifier">return_internal_reference</span></code>
          static functions</a>
</h4></div></div></div>
<pre class="programlisting"><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">postcall</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">args</span><span class="special">,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">result</span><span class="special">);</span></pre>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Requires</span></dt>
<dd><p>
                  <code class="computeroutput"><span class="identifier">PyTuple_Check</span><span class="special">(</span><span class="identifier">args</span><span class="special">)</span>
                  <span class="special">!=</span> <span class="number">0</span></code>
                </p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
                  <a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward_st" title="Class with_custodian_and_ward static functions"><code class="computeroutput"><span class="identifier">with_custodian_and_ward_postcall</span><span class="special">::</span><span class="identifier">postcall</span><span class="special">(</span><span class="identifier">args</span><span class="special">,</span> <span class="identifier">result</span><span class="special">)</span></code></a>
                </p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.example"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_internal_ref.example" title="Example">Example</a>
</h4></div></div></div>
<p>
            C++ module definition:
          </p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">return_internal_reference</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>

<span class="keyword">class</span> <span class="identifier">Bar</span>
<span class="special">{</span>
 <span class="keyword">public</span><span class="special">:</span>
   <span class="identifier">Bar</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">x</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">{}</span>
   <span class="keyword">int</span> <span class="identifier">get_x</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span>
   <span class="keyword">void</span> <span class="identifier">set_x</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">{</span> <span class="keyword">this</span><span class="special">-&gt;</span><span class="identifier">x</span> <span class="special">=</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span>
 <span class="keyword">private</span><span class="special">:</span>
   <span class="keyword">int</span> <span class="identifier">x</span><span class="special">;</span>
<span class="special">};</span>

<span class="keyword">class</span> <span class="identifier">Foo</span>
<span class="special">{</span>
 <span class="keyword">public</span><span class="special">:</span>
   <span class="identifier">Foo</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">b</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">{}</span>

   <span class="comment">// Returns an internal reference</span>
   <span class="identifier">Bar</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">get_bar</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">b</span><span class="special">;</span> <span class="special">}</span>

 <span class="keyword">private</span><span class="special">:</span>
   <span class="identifier">Bar</span> <span class="identifier">b</span><span class="special">;</span>
<span class="special">};</span>

<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span>
<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">internal_refs</span><span class="special">)</span>
<span class="special">{</span>
   <span class="identifier">class_</span><span class="special">&lt;</span><span class="identifier">Bar</span><span class="special">&gt;(</span><span class="string">"Bar"</span><span class="special">,</span> <span class="identifier">init</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;())</span>
      <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"get_x"</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">Bar</span><span class="special">::</span><span class="identifier">get_x</span><span class="special">)</span>
      <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"set_x"</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">Bar</span><span class="special">::</span><span class="identifier">set_x</span><span class="special">)</span>
      <span class="special">;</span>

   <span class="identifier">class_</span><span class="special">&lt;</span><span class="identifier">Foo</span><span class="special">&gt;(</span><span class="string">"Foo"</span><span class="special">,</span> <span class="identifier">init</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;())</span>
      <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"get_bar"</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">Foo</span><span class="special">::</span><span class="identifier">get_bar</span>
          <span class="special">,</span> <span class="identifier">return_internal_reference</span><span class="special">&lt;&gt;())</span>
      <span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
            Python code:
          </p>
<pre class="programlisting"><span class="special">&gt;&gt;&gt;</span> <span class="identifier">from</span> <span class="identifier">internal_refs</span> <span class="identifier">import</span> <span class="special">*</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">f</span> <span class="special">=</span> <span class="identifier">Foo</span><span class="special">(</span><span class="number">3</span><span class="special">)</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">b1</span> <span class="special">=</span> <span class="identifier">f</span><span class="special">.</span><span class="identifier">get_bar</span><span class="special">()</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">b2</span> <span class="special">=</span> <span class="identifier">f</span><span class="special">.</span><span class="identifier">get_bar</span><span class="special">()</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">b1</span><span class="special">.</span><span class="identifier">get_x</span><span class="special">()</span>
<span class="number">3</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">b2</span><span class="special">.</span><span class="identifier">get_x</span><span class="special">()</span>
<span class="number">3</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">b1</span><span class="special">.</span><span class="identifier">set_x</span><span class="special">(</span><span class="number">42</span><span class="special">)</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">b2</span><span class="special">.</span><span class="identifier">get_x</span><span class="special">()</span>
<span class="number">42</span>
</pre>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_value_policy"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_value_policy" title="boost/python/return_value_policy.hpp">boost/python/return_value_policy.hpp</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_value_policy.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_value_policy.class_template_return_value_poli">Class
          template <code class="computeroutput"><span class="identifier">return_value_policy</span></code></a></span></dt>
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_value_policy.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_value_policy.introduction"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_value_policy.introduction" title="Introduction">Introduction</a>
</h4></div></div></div>
<p>
            return_value_policy instantiations are simply models of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a> which are composed
            of a <a class="link" href="../concepts/resultconverter.html#concepts.resultconverter.resultconvertergenerator_concept" title="ResultConverterGenerator Concept Requirements"><code class="computeroutput"><span class="identifier">ResultConverterGenerator</span></code></a> and
            optional <code class="computeroutput"><span class="identifier">Base</span></code> <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a>.
          </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_value_policy.class_template_return_value_poli"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_value_policy.class_template_return_value_poli" title="Class template return_value_policy">Class
          template <code class="computeroutput"><span class="identifier">return_value_policy</span></code></a>
</h4></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                    <p>
                      Parameter
                    </p>
                  </th>
<th>
                    <p>
                      Requirements
                    </p>
                  </th>
<th>
                    <p>
                      Default
                    </p>
                  </th>
</tr></thead>
<tbody>
<tr>
<td>
                    <p>
                      ResultConverterGenerator
                    </p>
                  </td>
<td>
                    <p>
                      A model of <a class="link" href="../concepts/resultconverter.html#concepts.resultconverter.resultconvertergenerator_concept" title="ResultConverterGenerator Concept Requirements"><code class="computeroutput"><span class="identifier">ResultConverterGenerator</span></code></a>
                    </p>
                  </td>
<td>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      Base
                    </p>
                  </td>
<td>
                    <p>
                      A model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a>
                    </p>
                  </td>
<td>
                    <p>
                      default_call_policies
                    </p>
                  </td>
</tr>
</tbody>
</table></div>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span>
<span class="special">{</span>
  <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">ResultConverterGenerator</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Base</span> <span class="special">=</span> <span class="identifier">default_call_policies</span><span class="special">&gt;</span>
  <span class="keyword">struct</span> <span class="identifier">return_value_policy</span> <span class="special">:</span> <span class="identifier">Base</span>
  <span class="special">{</span>
      <span class="keyword">typedef</span> <span class="identifier">ResultConverterGenerator</span> <span class="identifier">result_converter</span><span class="special">;</span>
  <span class="special">};</span>
<span class="special">}}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_return_value_policy.example"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_return_value_policy.example" title="Example">Example</a>
</h4></div></div></div>
<p>
            C++ module definition:
          </p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">module</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="keyword">class</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">copy_const_reference</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">python</span><span class="special">/</span><span class="identifier">return_value_policy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>

<span class="comment">// classes to wrap</span>
<span class="keyword">struct</span> <span class="identifier">Bar</span> <span class="special">{</span> <span class="keyword">int</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span>

<span class="keyword">struct</span> <span class="identifier">Foo</span> <span class="special">{</span>
   <span class="identifier">Foo</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">:</span> <span class="special">{</span> <span class="identifier">b</span><span class="special">.</span><span class="identifier">x</span> <span class="special">=</span> <span class="identifier">x</span><span class="special">;</span> <span class="special">}</span>
   <span class="identifier">Bar</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">get_bar</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">b</span><span class="special">;</span> <span class="special">}</span>
 <span class="keyword">private</span><span class="special">:</span>
   <span class="identifier">Bar</span> <span class="identifier">b</span><span class="special">;</span>
<span class="special">};</span>

<span class="comment">// Wrapper code</span>
<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">python</span><span class="special">;</span>
<span class="identifier">BOOST_PYTHON_MODULE</span><span class="special">(</span><span class="identifier">my_module</span><span class="special">)</span>
<span class="special">{</span>
   <span class="identifier">class_</span><span class="special">&lt;</span><span class="identifier">Bar</span><span class="special">&gt;(</span><span class="string">"Bar"</span><span class="special">);</span>

   <span class="identifier">class_</span><span class="special">&lt;</span><span class="identifier">Foo</span><span class="special">&gt;(</span><span class="string">"Foo"</span><span class="special">,</span> <span class="identifier">init</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;())</span>
      <span class="special">.</span><span class="identifier">def</span><span class="special">(</span><span class="string">"get_bar"</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">Foo</span><span class="special">::</span><span class="identifier">get_bar</span>
          <span class="special">,</span> <span class="identifier">return_value_policy</span><span class="special">&lt;</span><span class="identifier">copy_const_reference</span><span class="special">&gt;())</span>
      <span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
            Python code:
          </p>
<pre class="programlisting"><span class="special">&gt;&gt;&gt;</span> <span class="identifier">from</span> <span class="identifier">my_module</span> <span class="identifier">import</span> <span class="special">*</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">f</span> <span class="special">=</span> <span class="identifier">Foo</span><span class="special">(</span><span class="number">3</span><span class="special">)</span>         <span class="special">#</span> <span class="identifier">create</span> <span class="identifier">a</span> <span class="identifier">Foo</span> <span class="identifier">object</span>
<span class="special">&gt;&gt;&gt;</span> <span class="identifier">b</span> <span class="special">=</span> <span class="identifier">f</span><span class="special">.</span><span class="identifier">get_bar</span><span class="special">()</span>    <span class="special">#</span> <span class="identifier">make</span> <span class="identifier">a</span> <span class="identifier">copy</span> <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">internal</span> <span class="identifier">Bar</span> <span class="identifier">object</span>
</pre>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_" title="boost/python/with_custodian_and_ward.hpp">boost/python/with_custodian_and_ward.hpp</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward">Class
          <code class="computeroutput"><span class="identifier">with_custodian_and_ward</span></code></a></span></dt>
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward_st">Class
          <code class="computeroutput"><span class="identifier">with_custodian_and_ward</span></code>
          static functions</a></span></dt>
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward_po">Class
          <code class="computeroutput"><span class="identifier">with_custodian_and_ward_postcall</span></code></a></span></dt>
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward_p0">Class
          <code class="computeroutput"><span class="identifier">with_custodian_and_ward_postcall</span></code>
          static functions</a></span></dt>
<dt><span class="section"><a href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.example">Example</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.introduction"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.introduction" title="Introduction">Introduction</a>
</h4></div></div></div>
<p>
            This header provides facilities for establishing a lifetime dependency
            between two of a function's Python argument or result objects. The ward
            object will not be destroyed until after the custodian as long as the
            custodian object supports <a href="http://www.python.org/doc/current/lib/module-weakref.html" target="_top">weak
            references</a> (Boost.Python extension classes all support weak references).
            If the custodian object does not support weak references and is not
            <code class="computeroutput"><span class="identifier">None</span></code>, an appropriate
            exception will be thrown. The two class templates <code class="computeroutput"><span class="identifier">with_custodian_and_ward</span></code>
            and <code class="computeroutput"><span class="identifier">with_custodian_and_ward_postcall</span></code>
            differ in the point at which they take effect.
          </p>
<p>
            In order to reduce the chance of inadvertently creating dangling pointers,
            the default is to do lifetime binding before the underlying C++ object
            is invoked. However, before invocation the result object is not available,
            so <code class="computeroutput"><span class="identifier">with_custodian_and_ward_postcall</span></code>
            is provided to bind lifetimes after invocation. Also, if a C++ exception
            is thrown after <code class="computeroutput"><span class="identifier">with_custodian_and_ward</span><span class="special">&lt;&gt;::</span><span class="identifier">precall</span></code>
            but before the underlying C++ object actually stores a pointer, the lifetime
            of the custodian and ward objects will be artificially bound together,
            so one might choose <code class="computeroutput"><span class="identifier">with_custodian_and_ward_postcall</span></code>
            instead, depending on the semantics of the function being wrapped.
          </p>
<p>
            Please note that this is not the appropriate tool to use when wrapping
            functions which transfer ownership of a raw pointer across the function-call
            boundary. Please see the FAQ if you want to do that.
          </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward" title="Class with_custodian_and_ward">Class
          <code class="computeroutput"><span class="identifier">with_custodian_and_ward</span></code></a>
</h4></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                    <p>
                      Parameter
                    </p>
                  </th>
<th>
                    <p>
                      Requirements
                    </p>
                  </th>
<th>
                    <p>
                      Description
                    </p>
                  </th>
<th>
                    <p>
                      Default
                    </p>
                  </th>
</tr></thead>
<tbody>
<tr>
<td>
                    <p>
                      custodian
                    </p>
                  </td>
<td>
                    <p>
                      A positive compile-time constant of <code class="computeroutput"><span class="identifier">type</span>
                      <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></code>.
                    </p>
                  </td>
<td>
                    <p>
                      The 1-based index of the parameter which is the dependency
                      in the lifetime relationship to be established. If used to
                      wrap a member function, parameter 1 is the target object (<code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>).
                      Note that if the target Python object type doesn't support
                      weak references, a Python TypeError exception will be raised
                      when the C++ object being wrapped is called.
                    </p>
                  </td>
<td>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      ward
                    </p>
                  </td>
<td>
                    <p>
                      A positive compile-time constant of type <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></code>.
                    </p>
                  </td>
<td>
                    <p>
                      The 1-based index of the parameter which is the dependent in
                      the lifetime relationship to be established. If used to wrap
                      a member function, parameter 1 is the target object (<code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>).
                    </p>
                  </td>
<td>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      Base
                    </p>
                  </td>
<td>
                    <p>
                      A model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a>
                    </p>
                  </td>
<td>
                    <p>
                      Used for policy <a class="link" href="../concepts.html#concepts.callpolicies.callpolicies_composition" title="CallPolicies Composition">composition</a>.
                    </p>
                  </td>
<td>
                    <p>
                      default_call_policies
                    </p>
                  </td>
</tr>
</tbody>
</table></div>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span>
<span class="special">{</span>
   <span class="keyword">template</span> <span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">custodian</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">ward</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Base</span> <span class="special">=</span> <span class="identifier">default_call_policies</span><span class="special">&gt;</span>
   <span class="keyword">struct</span> <span class="identifier">with_custodian_and_ward</span> <span class="special">:</span> <span class="identifier">Base</span>
   <span class="special">{</span>
      <span class="keyword">static</span> <span class="keyword">bool</span> <span class="identifier">precall</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">args</span><span class="special">);</span>
   <span class="special">};</span>
<span class="special">}}</span></pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward_st"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward_st" title="Class with_custodian_and_ward static functions">Class
          <code class="computeroutput"><span class="identifier">with_custodian_and_ward</span></code>
          static functions</a>
</h4></div></div></div>
<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">precall</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">args</span><span class="special">);</span></pre>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Requires</span></dt>
<dd><p>
                  <code class="computeroutput"><span class="identifier">PyTuple_Check</span><span class="special">(</span><span class="identifier">args</span><span class="special">)</span>
                  <span class="special">!=</span> <span class="number">0</span></code>
                </p></dd>
<dt><span class="term">Effects</span></dt>
<dd><p>
                  Makes the lifetime of the argument indicated by ward dependent
                  on the lifetime of the argument indicated by custodian.
                </p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
                  false and PyErr_Occurred() != 0 upon failure, true otherwise.
                </p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward_po"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward_po" title="Class with_custodian_and_ward_postcall">Class
          <code class="computeroutput"><span class="identifier">with_custodian_and_ward_postcall</span></code></a>
</h4></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                    <p>
                      Parameter
                    </p>
                  </th>
<th>
                    <p>
                      Requirements
                    </p>
                  </th>
<th>
                    <p>
                      Description
                    </p>
                  </th>
<th>
                    <p>
                      Default
                    </p>
                  </th>
</tr></thead>
<tbody>
<tr>
<td>
                    <p>
                      custodian
                    </p>
                  </td>
<td>
                    <p>
                      A positive compile-time constant of type <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></code>.
                    </p>
                  </td>
<td>
                    <p>
                      The index of the parameter which is the dependency in the lifetime
                      relationship to be established. Zero indicates the result object;
                      1 indicates the first argument. If used to wrap a member function,
                      parameter 1 is the target object (<code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>). Note that if the target
                      Python object type doesn't support weak references, a Python
                      TypeError exception will be raised when the C++ object being
                      wrapped is called.
                    </p>
                  </td>
<td>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      ward
                    </p>
                  </td>
<td>
                    <p>
                      A positive compile-time constant of type <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span></code>.
                    </p>
                  </td>
<td>
                    <p>
                      The index of the parameter which is the dependent in the lifetime
                      relationship to be established. Zero indicates the result object;
                      1 indicates the first argument. If used to wrap a member function,
                      parameter 1 is the target object (<code class="computeroutput"><span class="special">*</span><span class="keyword">this</span></code>).
                    </p>
                  </td>
<td>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      Base
                    </p>
                  </td>
<td>
                    <p>
                      A model of <a class="link" href="../concepts.html#concepts.callpolicies" title="CallPolicies"><code class="computeroutput"><span class="identifier">CallPolicies</span></code></a>
                    </p>
                  </td>
<td>
                    <p>
                      Used for policy <a class="link" href="../concepts.html#concepts.callpolicies.callpolicies_composition" title="CallPolicies Composition">composition</a>.
                    </p>
                  </td>
<td>
                    <p>
                      default_call_policies
                    </p>
                  </td>
</tr>
</tbody>
</table></div>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">python</span>
<span class="special">{</span>
   <span class="keyword">template</span> <span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">custodian</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">ward</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Base</span> <span class="special">=</span> <span class="identifier">default_call_policies</span><span class="special">&gt;</span>
   <span class="keyword">struct</span> <span class="identifier">with_custodian_and_ward_postcall</span> <span class="special">:</span> <span class="identifier">Base</span>
   <span class="special">{</span>
      <span class="keyword">static</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">postcall</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">args</span><span class="special">,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">result</span><span class="special">);</span>
   <span class="special">};</span>
<span class="special">}}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward_p0"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.class_with_custodian_and_ward_p0" title="Class with_custodian_and_ward_postcall static functions">Class
          <code class="computeroutput"><span class="identifier">with_custodian_and_ward_postcall</span></code>
          static functions</a>
</h4></div></div></div>
<pre class="programlisting"><span class="identifier">PyObject</span> <span class="special">*</span><span class="identifier">postcall</span><span class="special">(</span><span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">args</span><span class="special">,</span> <span class="identifier">PyObject</span><span class="special">*</span> <span class="identifier">result</span><span class="special">);</span></pre>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term">Requires</span></dt>
<dd><p>
                  <code class="computeroutput"><span class="identifier">PyTuple_Check</span><span class="special">(</span><span class="identifier">args</span><span class="special">)</span>
                  <span class="special">!=</span> <span class="number">0</span></code>,
                  <code class="computeroutput"><span class="identifier">result</span> <span class="special">!=</span>
                  <span class="number">0</span></code>
                </p></dd>
<dt><span class="term">Effects</span></dt>
<dd><p>
                  Makes the lifetime of the object indicated by ward dependent on
                  the lifetime of the object indicated by custodian.
                </p></dd>
<dt><span class="term">Returns</span></dt>
<dd><p>
                  <code class="computeroutput"><span class="number">0</span></code> and <code class="computeroutput"><span class="identifier">PyErr_Occurred</span><span class="special">()</span>
                  <span class="special">!=</span> <span class="number">0</span></code>
                  upon failure, <code class="computeroutput"><span class="keyword">true</span></code>
                  otherwise.
                </p></dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.example"></a><a class="link" href="models_of_callpolicies.html#function_invocation_and_creation.models_of_callpolicies.boost_python_with_custodian_and_.example" title="Example">Example</a>
</h4></div></div></div>
<p>
            The following example shows how <code class="computeroutput"><span class="identifier">with_custodian_and_ward_postcall</span></code>
            is used by the library to implement <code class="computeroutput"><span class="identifier">return_internal_reference</span></code>
          </p>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">owner_arg</span> <span class="special">=</span> <span class="number">1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Base</span> <span class="special">=</span> <span class="identifier">default_call_policies</span><span class="special">&gt;</span>
<span class="keyword">struct</span> <span class="identifier">return_internal_reference</span>
    <span class="special">:</span> <span class="identifier">with_custodian_and_ward_postcall</span><span class="special">&lt;</span><span class="number">0</span><span class="special">,</span> <span class="identifier">owner_arg</span><span class="special">,</span> <span class="identifier">Base</span><span class="special">&gt;</span>
<span class="special">{</span>
   <span class="keyword">typedef</span> <span class="identifier">reference_existing_object</span> <span class="identifier">result_converter</span><span class="special">;</span>
<span class="special">};</span>
</pre>
</div>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2002-2005, 2015 David Abrahams, Stefan Seefeld<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="function_documentation.html"><img src="../../images/prev.png" alt="Prev"></a><a accesskey="u" href="../function_invocation_and_creation.html"><img src="../../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../images/home.png" alt="Home"></a><a accesskey="n" href="models_of_resultconverter.html"><img src="../../images/next.png" alt="Next"></a>
</div>
</body>
</html>
